home *** CD-ROM | disk | FTP | other *** search
/ BBS Toolkit / BBS Toolkit.iso / rbbs_pc / rfm100.zip / RFM.DOC < prev    next >
Text File  |  1990-09-02  |  21KB  |  466 lines
  1.  
  2.              RBBS-PC Automatic File Area Maintenance (RFM)
  3.                               Version 1.0
  4.  
  5.                    Copyright 1990 by Warren Muldrow
  6.                                      The Software Designer
  7.                                      (912)-432-2440
  8.                                      RBBS-Net 8:928/1
  9.                                      Fido-Net 1:3617/1
  10.  
  11.  
  12. Introduction
  13.  
  14.     RFM takes advantage of the Fast File Search (FFS) capability of
  15. RBBS-PC version 17.3 to record the date that a caller last referenced
  16. each file on your BBS.  This allows unused files to be moved to archive
  17. areas to free up space on your disk drives.  Along the way, it provides
  18. a variety of housekeeping chores to automate the maintenance of your
  19. file areas and directories.  (RBBS-PC is copyrighted by D. Thomas Mack.)
  20.  
  21.     RFM provides these services:
  22.  
  23.     -  Rebuilds the file and location indexes for the RBBS-PC FFS.
  24.     -  Automatically moves files from Upload areas to Download areas.
  25.     -  Automatically moves files from Download areas to Archive areas.
  26.     -  Identifies duplicate file names.
  27.     -  Rebuilds either alphabetic or date ordered FMS directories.
  28.     -  Resizes the description length in FMS directories.
  29.     -  Removes duplicate FMS directory entries.
  30.     -  Flags or removes missing files from FMS directories.
  31.     -  Optionally adjusts dates for FMS directory entries.
  32.     -  Optionally adjusts file sizes for FMS directory entries.
  33.  
  34.  
  35. Overview
  36.  
  37.     RFM includes a modification to RBBSSUB4.BAS that adds a 3 character
  38. field to the FIDX file.  Each time a user views, downloads, or attempts
  39. to upload a file on your system, RFM places the current date in this
  40. field.  That allows RFM to detect files on your system that are not
  41. being used.  If disk space is a concern, RFM can automaticly move old
  42. and dusty files into a separate directory for you to copy to your
  43. archives at your leisure.
  44.  
  45.     RFM reads a control file that is compatible with the MAKEFIDX.DEF
  46. file that you are probably already using.  You may wish to edit your
  47. existing file to take advantage of some added capabilities that RFM
  48. provides.  A detailed description of the available parameters follows
  49. later in this document.
  50.  
  51.     RFM will scan the directories and paths you define in the control
  52. file to build an alphabetical list of files available for download.
  53. If the FMS directory is to be verified, it is also sorted into
  54. alphabetic sequence.  The new file list is then compared with the old
  55. file list (and optionally with the sorted FMS directory).
  56.  
  57.  
  58.                                     1
  59.  
  60.              RBBS-PC Automatic File Area Maintenance (RFM)
  61.  
  62.  
  63.     During this comparison, RFM moves files that have been present in
  64. the upload area for the specified number of days to the download area.
  65. Files in the download area that have not been referenced by a caller
  66. for the specified number of days are moved to an archive area.  If the
  67. directory into which files are moved is included in the paths to be
  68. searched, then the file will be kept in the new FIDX, and the FMS
  69. directory entry will remain unchanged.  Otherwise, the file is dropped
  70. from the FIDX, and the FMS directory entry can optionally be kept,
  71. dropped, or tagged as "archived."  Files found in the upload or download
  72. areas that are missing from the FMS directory are automatically added.
  73. Files listed in the FMS directory that are not found on disk may
  74. optionally be kept, dropped, or tagged as "missing."  RFM reports
  75. duplicate files on your disk and deletes duplicate files listed in the
  76. FMS directory.  (Here, only the newest FMS directory entry will be
  77. kept.)
  78.  
  79.     After the comparison is completed, the revised FMS directory is
  80. created.  If your FMS directory is in date sequence, you may optionally
  81. create a duplicate directory in alphabetic sequence to help build a
  82. downloadable text directory for your callers.  A companion program
  83. called MAKEDIR is ideal for creating downloadable file listings from
  84. alphabetic FMS directories.
  85.  
  86.     QSORT must be available either in the current directory or in a
  87. directory listed in the DOS "PATH" statement in order for RFM to
  88. execute.
  89.  
  90.  
  91. The Configuration File
  92.  
  93.     The default name for the configuration file is RFM.DEF.  RFM will
  94. look for this file in the current directory.  A different file name or
  95. directory can be specified on the command line.  Any configuration file
  96. parameters can be overriden by providing a different value for that
  97. parameter on the command line.
  98.  
  99.     Comments can be included in the configuration file.  Any line
  100. starting with an asterisk (*) is treated as a comment.  Any text
  101. following either a semicolon (;) or percent symbol (%) is treated as a
  102. comment.  Blank lines are also ignored.
  103.  
  104.     Parameters on the command line or in the configuration file may
  105. optionally begin with either a slash (/) or a hyphen (-), but neither is
  106. required.  All values may be given in either upper or lower case.  The
  107. parameters and their values may be separated by any combination of
  108. spaces, tabs or equals signs (=).  For example, the following three
  109. lines are all equivalent:
  110.  
  111.         /LocationFile=LIDX.DEF
  112.         -locationfile LIDX.DEF
  113.         LOCATIONFILE            lidx.def
  114.  
  115.  
  116.                                     2
  117.  
  118.              RBBS-PC Automatic File Area Maintenance (RFM)
  119.  
  120.  
  121. Getting Started
  122.  
  123.     The easiest way to start using RFM is to set up the RFM.DEF file
  124. with the least parameters needed for it to build the files needed by
  125. RBBS-PC's Fast File Search.  If you run RFM from the directory in which
  126. your FIDX and LIDX files are kept, you need only include the UPLOAD
  127. parameter for RBBS-PC's upload directory and one FILESPEC parameter for
  128. each of your download directories.  If you wish to keep RFM in a
  129. different directory, then you'll also need to include the NAMEFILE and
  130. LOCATIONFILE parameters.  If you have a large RAM drive, you probably
  131. will also want to include the WORKPATH parameter to get the fastest
  132. possible execution.
  133.  
  134.     Run RFM with this smallest configuration.  The first time you run
  135. RFM you should redirect the console output to a file that you can
  136. review later.  Using this configuration, the only messages that will
  137. be produced in this file will be warnings of duplicate files on your
  138. directories.  The command line should look like this:
  139.  
  140.         RFM >RFM.Log
  141.  
  142.     Now that you have a new FIDX, you need to install the modified
  143. copy of RBBS-PC.EXE that includes the patch provided for RBBSSUB4.  If
  144. you have not already deleted your download areas from CONFIG parameter
  145. 208, you should do this now.  RBBS-PC will search all directories
  146. listed in the download portion of parameter 208 before looking in the
  147. FIDX file.  If the dates are to be maintained in the FIDX, then RBBS-PC
  148. must use the FIDX to find the file.  If you want all uploads to be
  149. immediately available for download, then parameter 208 should list the
  150. upload directory in both the upload and download sections.  Otherwise,
  151. the download section should be blank to let all downloads go to the
  152. FIDX.
  153.  
  154.     Because the new FIDX file has longer records than RBBS-PC's original
  155. version, errors will occur if this patch has not been installed.  Run
  156. the new RBBS-PC and verify that it can successfully locate files by
  157. V)iewing or D)ownloading a file from one of your download areas.  Files
  158. located in your upload area, or in a directory listed in the download
  159. areas specified in CONFIG parameter 208 will not test the new
  160. modifications.  You also may wish to attempt to upload a file that is
  161. already on your system to be sure that it is recognized as a duplicate.
  162.  
  163.  
  164. Enabling FMS Directory Maintenance
  165.  
  166.     Now that the basics are in place, the rest of the work can be done
  167. at your lieisure.  To turn on FMS directory maintenance, the only
  168. required parameter for your RFM.DEF file is FMSFILE.  I strongly
  169. recommend, that the first time you run RFM with FMS directory
  170. maintenance installed, that you at least include an FMSMISSING entry to
  171. be sure you don't delete directory entries for a download path that you
  172.  
  173.  
  174.                                     3
  175.  
  176.              RBBS-PC Automatic File Area Maintenance (RFM)
  177.  
  178.  
  179. may have missed during the initial installation.  All the parameters
  180. that start with the letters FMS apply to FMS directory maintenance.
  181. You should review each of these to decide if you wish to use them.
  182.  
  183.  
  184. Enabling Automatic File Movement
  185.  
  186.     You can enable the automatic migration of files from upload areas to
  187. download areas by including the <days> and <path> options on your UPLOAD
  188. option in RFM.DEF.  Archiving is enabled by including these same options
  189. on the FILESPEC and FILEDIR lines.  For archiving, the BULLETIN option
  190. can be used to warn users of files that will soon be archived.  The
  191. FMSARCHIVE option determines how archived files will be treated when
  192. you use the FMS directory maintenance options.
  193.  
  194.  
  195. The Parameters
  196.  
  197.     BULLETIN
  198.  
  199.         The Bulletin parameter names a file into which the directory
  200.         entries for "dusty" files will be written.  Following the file
  201.         name, also add a <days> parameter.  The <days> will specify the
  202.         number of days BEFORE the file is archived that you wish to list
  203.         it in the bulletin.  This parameter is active ONLY if the FMS
  204.         file comparison is enabled by using the FMSFile parameter.
  205.         Directory lines written to the bulletin file will be appended to
  206.         the end of the existing file.  This allows you to use your own
  207.         text file as a header for the bulletin.
  208.  
  209.     FILEDIR
  210.  
  211.         This specifies a file containing a list of files that are
  212.         available for download.  It may be formatted either as a normal
  213.         RBBS-PC directory (either old style or FMS), or as the output
  214.         from a DOS "DIR" command.  In either case, it must contain a
  215.         line with the text "Directory of" followed by a path sepecifi-
  216.         cation or macro description.  The file may contain multiple
  217.         "Directory of" lines, which means that you can concatenate any
  218.         number of file directories together.  RFM will not validate the
  219.         path specified in these files.  The file size and date must be
  220.         included in the directory list.
  221.  
  222.         Recommendation:  By specifying a macro in the "Directory of"
  223.         line, you can let callers search file directories from other
  224.         local BBSs and tell the user who to call to find the file.
  225.  
  226.     FILESPEC
  227.  
  228.         The FileSpec parameters define your downloadable file areas.  If
  229.         only a path is given, then all files in that path are assumed to
  230.  
  231.  
  232.                                     4
  233.  
  234.              RBBS-PC Automatic File Area Maintenance (RFM)
  235.  
  236.  
  237.         be available for download.  Alternately, a wildcard file
  238.         specification or specific file name may be given.  Adding "/S"
  239.         after the pathname causes all unhidden subdirectories to be
  240.         searched for the same file specification.  Hidden and system
  241.         files will always be skipped.  Following the path name, you may
  242.         optionally include <days> and <path> that are described below.
  243.         If these parameters are used, files that have not been
  244.         referenced by callers (viewed, downloaded, or attempted uploads)
  245.         within the number of days specified will be moved to the <path>.
  246.         See the BULLETIN and FMSARCHIVE parameters for more information.
  247.  
  248.         Recommendation:  If disk space is tight, use the <days> and
  249.         <path> option to move "dusty" files to another directory on your
  250.         hard disk.  You can then back these files up to diskette and
  251.         recover the disk space that they used.  Combined with the
  252.         FMSArchive and FileDir options, you can use a macro to tell
  253.         you when users try to download archived files so that you can
  254.         restore them to your download directory.
  255.  
  256.     FMSCAT
  257.  
  258.         FMSCat provides the default FMS category code to be assigned to
  259.         all FMS directory entries that are created by RFM when it finds
  260.         files on your system that are not listed in the FMS directory.
  261.         The default value is "UNC."
  262.  
  263.     FMSALPHA
  264.  
  265.         FMSAlpha provides the name of a file that RFM will build that is
  266.         to contain an alphabetic FMS directory.  This file can then be
  267.         used to provide alphabetic master file lists for your users to
  268.         download.  If your primary FMS directory is in alphabetic
  269.         sequence, then this parameter will be ignored.  By default, no
  270.         alphabetic directory is created.  Comment entries (starting with
  271.         an asterisk) will be placed at the top of this file.
  272.  
  273.     FMSARCHIVE
  274.  
  275.         FMSArchive controls how FMS directory entries will be treated
  276.         when the file is moved from the download area to an archive area
  277.         AND the archive area is not listed as a downloadable area.  By
  278.         default, the directory entries will be deleted.  The same three
  279.         options described for FMSMissing are available for FMSArchive.
  280.  
  281.         Recommendation:  You may want to use the file name option here.
  282.         Remember that RBBS-PC can execute a macro when a file is
  283.         selected whose directory path starts with "M!".  By appending
  284.         the archived directory entries to a text file that is listed in
  285.         a FILEDIR parameter, you can use a macro that will list user
  286.         requests for archived files.
  287.  
  288.  
  289.  
  290.                                     5
  291.  
  292.              RBBS-PC Automatic File Area Maintenance (RFM)
  293.  
  294.  
  295.     FMSDATE
  296.  
  297.         This parameter controls what file date will be used in the FMS
  298.         directory.  By default, the newer of the actual file date or the
  299.         date in the old FMS directory will be used.  You may give any of
  300.         three values here:
  301.  
  302.             FMSDATE ACTUAL - to use the actual file date
  303.             FMSDATE FMS    - to use the date in the old FMS directory
  304.             FMSDATE NEWER  - to use the more recent of the two (default)
  305.  
  306.         Any of the three values may be abbrevieated with just the first
  307.         character (A, F, or N).
  308.  
  309.     FMSDESCLEN
  310.  
  311.         FMSDescLen specifies what description length should be used for
  312.         the new FMS directory.  RFM will automatically check the length
  313.         of the first line of the FMS directory and use the same descrip-
  314.         tion length that it finds in the old directory.  If you want to
  315.         change your description length, or need to reformat a bad
  316.         directory, specify the desired description length here.
  317.  
  318.     FMSFILE
  319.  
  320.         FMSFile is the name of the FMS directory that is to be compared
  321.         with the download areas and rebuilt.  By default, no FMS file
  322.         comparison is made.  RFM will detect the NOSORT option in the
  323.         first line of an alphabetically sequenced FMS directory and
  324.         automatically build the same sequence for its output.  If the
  325.         NOSORT option is not listed, the new FMS directory will be in
  326.         date sequence.  Date sequenced directories also will be sorted
  327.         so that files will be listed to the user alphabetically within
  328.         date.  To use this option, you MUST have a single FMS directory,
  329.         or at least separate download directories that correspond to
  330.         each separate FMS directory.  Chained FMS directories are
  331.         supported.
  332.  
  333.     FMSMISSIMG
  334.  
  335.         FMSMissing controls how FMS directory entries will be treated
  336.         when the file cannot be found in any of the specified
  337.         directories.  By default, these FMS directory entries will be
  338.         deleted.  You can specify any of three options here:
  339.  
  340.             Use just a period (.) to make RFM keep the directory entry
  341.             as it is.
  342.  
  343.             Give a file name to make RFM write missing directory entries
  344.             to a separate file.  Entries are appended to the existing
  345.             file in standard FMS format.
  346.  
  347.  
  348.                                     6
  349.  
  350.              RBBS-PC Automatic File Area Maintenance (RFM)
  351.  
  352.  
  353.             Provide a one word test (like "missing") to make RFM replace
  354.             the file size in the directory entry with this text.  The
  355.             text is limited to no more than 8 characters.
  356.  
  357.         Recommendation:  When you first try RFM, you may want to set
  358.         this to "missing" or "deleted".  Later, you may want to
  359.         change this to delete the directory entry.
  360.  
  361.     LOCATIONFILE
  362.  
  363.         LocationFile is the name of the list of paths that the file
  364.         index references and must also match the RBBS-PC configuration.
  365.         The default value is LIDX.DEF in the current directory.
  366.  
  367.     NAMEFILE
  368.  
  369.         NameFile is the name of the file index that RBBS-PC will look
  370.         for.  The default value is FIDX.DEF in the current directory.
  371.  
  372.     UPLOAD
  373.  
  374.         The Upload parameters define your upload file directories.  The
  375.         Upload parameters are identical to the FileSpec parameters and
  376.         work the same way except the way the <days> and <archive
  377.         path> are used.  If the path(s) you list here are
  378.         listed as available for download in your RBBS-PC configuration,
  379.         then the date recorded in the file index will remain as the date
  380.         the file was first discovered on your system by RFM.  If the
  381.         <days> and <archive path> are given for Upload areas, then the
  382.         uploaded files will be moved to the <archive path> after they
  383.         have been on your system for <days> number of days.
  384.  
  385.     WORKPATH
  386.  
  387.         The WorkPath parameter specifies a directory that RFM should use
  388.         for all of its working files.  Since temporary files have to be
  389.         built for the new file index and the extracted FMS directory,
  390.         and these working files have to be sorted, and the new FMS
  391.         directory sorted again, the use of a RAM disk for working files
  392.         can significantly speed things up.
  393.  
  394.     <days>
  395.  
  396.         The <days> option may be added to FileSpec or Upload to tell RFM
  397.         how old a file should be before it is moved.  It is given as a
  398.         simple decimal number.  Use -1 to ALWAYS move a file (this can
  399.         be useful for upload areas if you don't want to examine these
  400.         files) or 0 to NEVER move a file (this is useful to temporarily
  401.         "turn off" a file move).  <days> can be used on the Bulletin
  402.         parameter to indicate how many days BEFORE a file is archived
  403.         that its directory entry should be listed in the bulletin.
  404.  
  405.  
  406.                                     7
  407.  
  408.              RBBS-PC Automatic File Area Maintenance (RFM)
  409.  
  410.  
  411.     <path>
  412.  
  413.         The <path> option is added to FileSpec or Upload when you use
  414.         <days> to tell RFM where to move the file.
  415.  
  416.  
  417. The Date Codes
  418.  
  419.     The following table shows the codes used in the FIDX file to encode the
  420. date the file was last referenced.  The date appears as three ASCII
  421. characters corresponding to year, month and day.
  422.  
  423.     Decimal     Character       Year        Month       Day
  424.       32         <space>         80           1          1
  425.       33            !            81           2          2
  426.       34            "            82           3          3
  427.       35            #            83           4          4
  428.       36            $            84           5          5
  429.       37            %            85           6          6
  430.       38            &            86           7          7
  431.       39            '            87           8          8
  432.       40            (            88           9          9
  433.       41            )            89          10         10
  434.       42            *            90          11         11
  435.       43            +            91          12         12
  436.       44            ,            92                     13
  437.       45            -            93                     14
  438.       46            .            94                     15
  439.       47            /            95                     16
  440.       48            0            96                     17
  441.       49            1            97                     18
  442.       50            2            98                     19
  443.       51            3            99                     20
  444.       52            4            00                     21
  445.       53            5            01                     22
  446.       54            6             .                     23
  447.       55            7             .                     24
  448.       56            8             .                     25
  449.       57            9                                   26
  450.       58            :                                   27
  451.       59            ;                                   28
  452.       60            <                                   29
  453.       61            =                                   30
  454.       62            >                                   31
  455.  
  456.  
  457. Footnote
  458.  
  459.     RFM may be freely used and distributed.  Questions and comments are
  460. welcome.  I hope you will find RFM as valuable to your system as I do
  461. to mine.
  462.  
  463.  
  464.                                     8
  465.  
  466.